feat: animations - #45

WARNING: 1000 lines for new configs only, the pr is only 1000 lines

Animation system overview

The system has four files with clear responsibilities: bone.hpp handles keyframe data and interpolation, skeleton.hpp owns the bone registry and node hierarchy, animation.hpp wraps an assimp animation into channels, and animator.hpp drives playback each frame.

bone.hpp — BoneAnimation

Each bone's animation is stored as three independent keyframe tracks: positions (glm::vec3), rotations (glm::quat), scales (glm::vec3). The interpolate(t) method finds the two keyframes bracketing the current time via findIndex, computes a normalized factor between them, then runs glm::mix for position/scale and glm::slerp for rotation (slerp takes the shortest arc on the quaternion sphere). The result is composed into a single mat4 via translate × rotate × scale.

skeleton.hpp — Skeleton + SkeletonNode

Skeleton holds two things: a boneInfoMap mapping bone names → BonePose (an integer ID + offsetMatrix), and a flat nodes vector of SkeletonNode. The flat vector is topologically sorted — parents always appear before children — which lets the animator traverse it with a plain for loop instead of recursion. The offsetMatrix is the inverse of a bone's bind-pose world transform; it moves vertices from world space into the bone's local space before the animated transform is applied.

animation.hpp — Animation

Thin wrapper around aiAnimation. The constructor reads duration, ticks-per-second (defaulting to 25 if assimp returns 0), and iterates mChannels to build a BoneAnimation per node, stored in a channels map keyed by node name.

animator.hpp — Animator::computeBoneTransform

This is the core loop. For each node in topological order:

1. Start with the node's bind-pose localTransform
2. If channels has an entry for this node name, replace it with channel.interpolate(currentTime)
3. Accumulate: globalTransforms[i] = globalTransforms[parentIndex] * localTransform (root uses localTransform directly)
4. Cache in nodeTransforms by name (for non-skinned nodes like attached meshes or lights)
5. If this node is a registered bone, write finalBoneMatrices[id] = globalInverseTransform * globalTransforms[i] * offsetMatrix

finalBoneMatrices is the uniform array sent to the vertex shader. Each vertex stores up to N bone IDs and weights; the shader computes a weighted sum of those matrices to get the final vertex position.

Things worth reviewing

MAX_BONES 110 is a hard cap — worth confirming the target models don't exceed it, since overflow is silent (the id < finalBoneMatrices.size() check just skips the bone). The speed multiplier in update scales ticksPerSecond directly, so a speed of 2.0 doubles playback rate. isFinished() only fires on non-looping animations once currentTime >= duration.

note: if you didn't notice by now but this comment is generated by claude, if you need to understand anything ask me